Переопределяемые и поставляемые объекты библиотеки

Область применения: управляемое приложение, мобильное приложение, обычное приложение.

1. С точки зрения возможностей по настройке функциональности библиотеки для работы в конкретной конфигурации-потребителе все объекты библиотеки условно делятся на три категории:

• Непереопределяемые объекты – «готовые» объекты, которые можно брать и использовать в конфигурации-потребителе «как есть». Их не следует изменять в конфигурации-потребителе, чтобы они были гарантированно одинаковы во всех конфигурациях, основывающихся на данной библиотеке. Более того, такие объекты обязательно должны присутствовать в конфигурациях, использующих библиотеку. Примеры: справочник Пользователи. 
• Переопределяемые объекты – «изменяемые» объекты для настройки библиотеки под конкретную конфигурацию. Они могут или должны быть изменены в конфигурации-потребителе. С помощью таких объектов решаются задачи изменения поведения библиотечной функциональности, ее параметризации спецификой конфигурации-потребителя, а также для подключения библиотечной функциональности к объектам конфигурации-потребителя.
• Определители типов – объекты-«классификаторы», которые не имеют базовой реализации. Предназначены для формирования единого пространства имен в конфигурациях, а реализация при этом может как угодно сильно различаться в конфигурациях-потребителях. Например: справочники-классификаторы, в которых  определено только «название»; сущность «организация» должна быть везде представлена справочником с именем Организации и т.п.

2. Рекомендуется устанавливать для объектов этих категорий следующие правила поставки:

• Непереопределяемые объекты – «изменения не рекомендуются»;
• Переопределяемые объекты и определители типов – «изменения разрешены».

Эти рекомендации продиктованы следующими соображениями:

• Непереопределяемые объекты – это зона ответственности разработчиков библиотеки, поэтому они не должны разрабатываться «по месту» в конфигурациях-потребителях. Но если необходимость изменений носит срочный характер (например, исправление критичной ошибки) или продиктована какими-то другими особыми соображениями, то допускается вносить изменения в непереопределяемые библиотечные объекты непосредственно в конфигурациях-потребителях. При этом нужно иметь в виду, что эти изменения могут быть потеряны при следующем обновлении версии библиотеки в конфигурации-потребителе, если не принять специальные меры (донести до разработчиков библиотеки необходимость внесения изменений или задокументировать этот отход от общей инструкции по обновлению библиотеки).
• Переопределяемые объекты и определители типы должны или могут быть изменены в конфигурации-потребителе, исходя из их назначения.

3. Для того чтобы упростить настройку библиотеки и снизить трудоемкость последующих обновлений версии библиотеки в конфигурации-потребителе следует минимизировать количество переопределяемых объектов с помощью следующих методик:

• Настройка состава типов переопределяемых реквизитов (свойств) тех или иных объектов библиотеки – для подключения библиотечной функциональности к объектам конфигурации-потребителя.
  Например: можно подключить библиотечную функциональность к конкретным объектам конфигурации с помощью расширения состава типов общей команды, измерения составного типа в регистре сведений и т.п.
  
• Добавление предопределенных элементов – для параметризации библиотечной функциональности спецификой конфигурации-потребителя.
  Например: для библиотечной подсистемы ведения и обработки контактной информации с помощью предопределенных элементов библиотечного справочника ВидыКонтактнойИнформации можно указать, какие виды контактной информации (телефон, адрес, электронный адрес и т.п.) должны быть предусмотрены для объектов конфигурации-потребителя.
  
• Переопределяемые общие модули – для изменения поведения библиотечной функциональности в конкретной конфигурации-потребителе 
  • с помощью переопределения тех или иных «обработчиков событий», предоставляемых библиотекой; например:
    ПриПодготовкеМакетаОписанияОбновлений
    ПриЗаписиСпискаБизнесПроцессов
  • а также для того, чтобы сообщить ту или иную информацию из конфигурации-потребителя в библиотеку. Например:
    ПриОпределенииБазовойВерсииКонфигурации
    ПриДобавленииОбработчиковОбновления

3.1. Переопределяемые общие модули следует называть с постфиксом Переопределяемый.

См. также: правила создания общих модулей

3.2. Переопределяемые общие модули должны содержать только экспортные процедуры, которые вызываются из кода самой библиотеки. Другими словами, не следует допускать вызовов процедур переопределяемых модулей непосредственно из кода конфигурации-потребителя.

Такое ограничение обусловлено соображением повышения устойчивости кода конфигурации, который вызывает библиотечные процедуры и функции, составляющие программный интерфейс библиотеки. К программному интерфейсу библиотеки следует относить только экспортные процедуры и функции непереопределяемых общих модулей.

Например, в библиотеке имеются модули ПапкиФайлов и ПапкиФайловПереопределяемый. Для использования в конфигурациях-потребителях в модуле ПапкиФайлов реализуется экспортная функция:

Функция ПапкаФайлов(ВладелецФайловСсылка) Экспорт

  СтандартнаяОбработка = Истина;
  Результат = Неопределено;
  ПапкиФайловПереопределяемый.ПриПолученииПапкиФайлов(ВладелецФайловСсылка, Результат, СтандартнаяОбработка);

  Если СтандартнаяОбработка Тогда
    // реализация по умолчанию
    Результат = ...
  КонецЕсли;
  Возврат Результат;

КонецФункции

а в модуле ПапкиФайловПереопределяемый - процедура-обработчик ПриПолученииПапкиФайлов:

// Вызывается из библиотеки при необходимости получить папку файлов для указанного владельца.
//
// Параметры:
//  ВладелецФайловСсылка – ЛюбаяСсылка                  - владелец файлов, для которого нужно вернуть папку.
//  ПапкаФайлов          – СправочникСсылка.ПапкиФайлов - в этот параметр нужно записать результат.
//  СтандартнаяОбработка – Булево                       - по умолчанию, Истина. В этом случае папка будет получена способом по умолчанию.
// Если значение параметра установить в Ложь, то в этой процедуре можно реализовать свой способ,
// которым в конфигурации получают папки файлов.
//
Процедура ПриПолученииПапкиФайлов(ВладелецФайловСсылка, ПапкаФайлов, СтандартнаяОбработка) Экспорт

КонецПроцедуры

При этом все вызовы из конфигурации-потребителя должны идти только к библиотечному модулю ПапкиФайлов. Обращение к ПапкиФайловПереопределяемый разрешается только из библиотечного модуля ПапкиФайлов.

3.3. При этом в переопределяемом модуле следует располагать только экспортные процедуры с пустой реализацией. В нем не должно быть каких-либо других не-экспортных процедур или функций. Базовую реализацию переопределяемых процедур следует располагать в непереопределяемом коде.

Такое ограничение вызвано необходимостью снизить трудоемкость последующих обновлений переопределяемых модулей в конфигурации-потребителе.
Например, неправильно поставлять переопределяемый модуль МояБиблиотекаПереопределяемый с какой-либо реализацией:

Функция НастройкаПараметровРаботы() Экспорт
 
 ПараметрыРаботы = Новый Структура;
 // если настройки по умолчанию не подходят, то измените их.
 ПараметрыРаботы.Вставить("ПоказыватьЕдинственныйРаздел",     Ложь);
 ПараметрыРаботы.Вставить("ЗадаватьДатуДляПрочихРазделов",    Ложь);
 ПараметрыРаботы.Вставить("ИспользоватьВнешнихПользователей", Ложь);
 Возврат ПараметрыРаботы;

КонецФункции

правильно:

// Позволяет настроить работу подсистемы.
//
// Параметры:
//  ПараметрыРаботы - Структура - содержит свойства:
//    * ПоказыватьЕдинственныйРаздел     - Булево - по умолчанию Ложь.
//    * ЗадаватьДатуДляПрочихРазделов    - Булево - по умолчанию Ложь.
//    * ИспользоватьВнешнихПользователей - Булево - по умолчанию Ложь.
//
Процедура ПриПолученииНастроекПараметровРаботы(ПараметрыРаботы) Экспорт

КонецПроцедуры

а установку значений по умолчанию перенести в общий модуль библиотеки:

Функция НастройкаПараметровРаботы()

 ПараметрыРаботы = Новый Структура;
 // настройки по умолчанию
 ПараметрыРаботы.Вставить("ПоказыватьЕдинственныйРаздел",     Ложь);
 ПараметрыРаботы.Вставить("ЗадаватьДатуДляПрочихРазделов",    Ложь);
 ПараметрыРаботы.Вставить("ИспользоватьВнешнихПользователей", Ложь);

 // а теперь запросим конфигурацию-потребитель на случай,
 // если эти умолчания не устраивают
 МояБиблиотекаПереопределяемый.ПриПолученииНастроекПараметровРаботы(ПараметрыРаботы);
 Возврат ПараметрыРаботы;

КонецФункции

3.4. При обновлении версии библиотеки в конфигурации-потребителе особого внимания требуют модули корневого объекта конфигурации и переопределяемые общие модули, так как автоматическое обновление таких «узких мест» конфигурации-потребителя невозможно. Для настройки в конфигурации переопределяемых общих модулей рекомендуется придерживаться общего подхода:

• При первой настройке переопределяемого общего модуля следует ознакомиться с документацией к его экспортным процедурам и функциям, приведенной в комментариях к ним. И при необходимости вписать реализацию в экспортные процедуры и функции модуля. 
• При каждом обновлении переопределяемого общего модуля требуется перенести новые экспортные процедуры и функции, удалить устаревшие и убедиться, что комментарии, количество и имена параметров у всех функций совпадают с их библиотечными эквивалентами. При необходимости вписать реализацию в новые экспортные процедуры и функции модуля, а также актуализировать реализацию уже существующих функций, если в новой версии библиотеки было изменено их назначение или состав параметров.

См. также